The amarok Smart DJ plug-in

by Rudd-O

"...you knew your own radio station was there - we're just helping you discover it."


	What the heck is this? What's this useful for?

You already know how powerful amaroK's search and playlist management capabilities are.  Just imagine how cool it would be to find songs that sounds like the one you're listening to, right now.  Similar genre, similar sound, similar tempo.  Now imagine this: you start playing one of your favorite songs, and, as time goes by, amaroK adds similar songs to your playlist, maintaining the mood.  Not just "songs someone else found similar", but songs that truly sound alike, same genre, same mood, same tempo.

That's what Smart DJ does.  Fantastic playlists, sorted by tempo, or song similarity, the sky is the limit. Host a party and prepare a great playlist in no time, in advance.  Or start with a good song, and let amaroK Smart DJ's Auto DJ feature do the rest.  Or scratch on your favorite DJ program, and Smart DJ will let you find what to play next real quick.

This plug-in is perfect for DJs who want to plan good sets of songs and playlists for live performance.  This plug-in is also perfect for people who hate making playlists, or hate the predictibility of hearing a playlist, or hate amaroK's Dynamic mode tendency to add songs that ruin the mood.


	So, how do I use this?

First, read "What do I need to use this plug-in?" below.

Did you read it?

...okay, so you read it and obeyed it.  Let's get to using this.

To use this, install it through your Scripts manager in amaroK, then select it from the list and click Run.  If everything is OK, you'll see a pop-up saying "Smart DJ is analyzing your collection".  Be very, very patient, because analyzing each song takes a minimum of 20 seconds.

If you want to know how far along the analysis is, you can select the plug-in in the Scripts manager and click Configure, a small window with a progress bar will appear.  Note that this requires GTK+ and PyGTK (you *did* read that section of this README, right?).

After (most of) the collection has been analyzed, you can right-click on a song in your playlist and select:
	"Smart DJ"->"Find songs similar to selection"
to get a list of songs sorted by similarity against the one you selected.  This also requires GTK+ and PyGTK.

Tip: although you can't normally see the tempo of songs in the standard version of amaroK, a special patch is distributed with this plug-in.  If you know how to patch amaroK's source code and recompile it from scratch, you can apply the patch, which will add a new column named "Tempo" in the playlist.

To use Auto DJ, select the plug-in in the Scripts manager and click Configure.  The Auto DJ options are self-explanatory: all you need to do is enable it, configure to your taste, and start playing a song that's already been analyzed (this is hard to tell unless you've patched amaroK to show the Tempo column, I know, I know.  I'm working on a solution).  This also requires GTK+ and PyGTK.


	How does it work?

We do this by analyzing the songs in your collection, collecting tempo and frequency distribution from each song and storing the information in the collection database.


	What do I need to use this plug-in?

A variety of things.  You need to have:

- amaroK 1.3.1 or higher
- a working installation of Python
- attr (getfattr and setfattr commands)
- a Python package called python-extattr
- a Python package called python-commandsplus
- (optional) support for extended attributes on your file systems
- the songanalysis program (which analyzes the songs)
- mpg321 (to analyze MP3)
- ogg321 (to analyze Ogg Vorbis files)

Of those, all are available on the Internet, as source packages
and as precompiled RPM packages.

Optional activities:

- install GTK+ 2.6 or above and PyGTK
This plug-in requires these packages for the user interface
- patch amaroK with the included patch named amarok-show-tempo.diff
This will let you see song tempo in a playlist column

Note that extended attributes are *optional*.  But not enabling
them may prove detrimental to this package's performance.  What
is mandatory is the presence of the python-extattr package, along
with the getfattr and setfattr commands.


	How do I turn on this "extended attributes" thing?

That's rather easy.

Each file system needs to be mounted with an extra option
called 'user_xattr'.  To see if this is supported on your
system, issue the following command on a command prompt,
as root:

   mount / -o remount,user_xattr

If you do not get any error message, then you're all set: you
have extended attribute support.  Do the command for all other
file systems where you store your songs (use the 'mount'
command alone to find out about the rest of your file systems).

To make this change permanent (across system restarts), edit
the /etc/fstab file and change the mount options field (for
each file system where you have your songs), adding
'user_xattr' where appropriate, or replacing the 'defaults'
keyword by 'user_xattr'.

By the way, this will be notoriously impossible to do if you're
using a Windows (VFAT) file system to store your music files.
VFAT file systems have no support for extended attributes at
all.  Do yourself a favor and reformat your disk to use either
ReiserFS, ext3 or another true UNIX file system.

Remember, extended attributes are optional.


	Why are extended attributes used?

Analyzing a song takes quite a while (about 30 seconds for each
song).

If you moved your song files to a new directory, and the
analysis results were stored only in the collection database,
this plug-in would need to analyze each song again, because
since the path to the file changed, there would be no way to
correlate the already stored information to the new file
location.

So, to alleviate this problem, this plug-in stores the analysis
results on extended attributes, so when a file is about to be
analyzed we can check whether the analysis was already
performed on that file and then simply collect the analysis
results, saving you time and electricity.

This is not infallible, of course.  If you had file /a/b/c.mp3
and you delete it, replacing it with another file at exactly
the same /a/b/c.mp3 location but a different content (and, of
course, different attributes) this plug-in won't detect the
special case.  There is a solution, but I'm quite lazy to
start working on it just about right now.

And, by the way, if you actually rename a file on disk, or move
it somewhere else (in your collection folders, of course) even
though amaroK would still show that file on your collection
browser, you would lose your statistics for that song (play
counter, last play date and rating).  This is a bug in amaroK.

I'm working on a long-term solution to this problem.